openapi: 3.0.1
info:
  title: Custom Apps API
  description: Provides access to apps that are installed in an organization.
  version: '1.0'
servers:
  - url: https://api.hyperproof.app/v1/customapps
    description: Hyperproof US
  - url: https://api.hyperproofgov.app/v1/customapps
    description: Hyperproof Gov
  - url: https://api.hyperproof.eu/v1/customapps
    description: Hyperproof EU
security:
  - oauth2: []
paths:
  /:
    get:
      summary: Get Custom Apps
      description: >
        `GET /`


        #### Description


        Retrieves details of custom apps installed in an organization, including
        their configurations, statuses, and integration metadata.
      operationId: get
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomAppCollection'
              example:
                - appId: string
                  appType: hypersync
                  isCustom: true
                  orgId: string
                  packageName: string
                  packageVersion: '1.0'
                  deploymentStatus: deployed
                  createdBy: string
                  createdOn: string
                  updatedBy: string
                  updatedOn: string
                  status: active
    post:
      summary: Add Custom App
      description: >-
        `POST /`


        #### Description


        Creates and registers a new custom app within an organization, storing
        details such as the app’s name, configuration, and integration
        parameters.
      operationId: post
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomApp'
              example:
                appId: string
                appType: hypersync
                isCustom: true
                orgId: string
                packageName: string
                packageVersion: '1.0'
                deploymentStatus: deployed
                createdBy: string
                createdOn: string
                updatedBy: string
                updatedOn: string
                status: active
  /{appId}:
    get:
      summary: Get Custom App
      description: >
        `GET /{appId}`


        #### Description


        Retrieves details of a specific custom app installed in an organization,
        including its configuration, status, and integration metadata.
      operationId: get-appid
      parameters:
        - name: appId
          in: path
          description: Unique ID of the custom app.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomApp'
              example:
                appId: string
                appType: hypersync
                isCustom: true
                orgId: string
                packageName: string
                packageVersion: '1.0'
                deploymentStatus: deployed
                createdBy: string
                createdOn: string
                updatedBy: string
                updatedOn: string
                status: active
    patch:
      summary: Update Custom App
      description: >
        `PATCH /{appId}`


        #### Description


        Updates the configuration or metadata of a custom app installed in an
        organization, allowing modifications to settings, permissions, or
        integration details.
      operationId: patch-appid
      parameters:
        - name: appId
          in: path
          description: Unique ID of the custom app.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomApp'
              example:
                appId: string
                appType: hypersync
                isCustom: true
                orgId: string
                packageName: string
                packageVersion: '1.0'
                deploymentStatus: deployed
                createdBy: string
                createdOn: string
                updatedBy: string
                updatedOn: string
                status: active
    delete:
      summary: Deletes Custom App
      description: >-
        `DEL /{appId}`


        #### Description


        Removes an existing custom app from an organization, permanently
        deleting its configuration, metadata, and associated integrations.
      operationId: delete-appid
      parameters:
        - name: appId
          in: path
          description: Unique ID of the custom app.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomApp'
              example:
                appId: string
                appType: hypersync
                isCustom: true
                orgId: string
                packageName: string
                packageVersion: '1.0'
                deploymentStatus: deployed
                createdBy: string
                createdOn: string
                updatedBy: string
                updatedOn: string
                status: active
  /{appId}/events:
    get:
      summary: Get Custom App Events
      description: >
        `GET /{appId}/events`


        #### Description


        Retrieves log events generated by a specified custom app, providing
        details such as timestamps, event types, and messages for monitoring and
        troubleshooting.
      operationId: get-appid-events
      parameters:
        - name: appId
          in: path
          description: Unique ID of the custom app.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogEventCollection'
              example:
                - id: string
                  timestamp: string
                  level: info
                  message: string
                  detail: string
                  orgId: string
                  userId: string
  /{appId}/stats:
    get:
      summary: Get  Custom App Statistics
      description: >
        `GET /{appId}/stats`


        #### Description


        Retrieves usage and performance statistics for a specified custom app,
        including metrics such as request counts, error rates, and response
        times.
      operationId: get-appid-stats
      parameters:
        - name: appId
          in: path
          description: Unique ID of the custom app.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomApp'
              example:
                appId: string
                appType: hypersync
                isCustom: true
                orgId: string
                packageName: string
                packageVersion: '1.0'
                deploymentStatus: deployed
                createdBy: string
                createdOn: string
                updatedBy: string
                updatedOn: string
                status: active
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://accounts.hyperproof.app/oauth/token
          scopes:
            organization.read: Grants read access to organizations
            organization.update: Grants update access to organizations
  schemas:
    CustomApp:
      type: object
      properties:
        appId:
          type: string
          format: uuid
          description: The unique identifier for the custom app.
        appType:
          type: string
          description: The type of custom app.
          enum:
            - hypersync
            - taskIntegration
            - folderIntegration
        isCustom:
          type: boolean
          description: Indicates whether the app is custom.
        orgId:
          type: string
          format: uuid
          description: >-
            The unique identifier for the organization the custom app belongs
            to.
        packageName:
          type: string
          description: The package name of the custom app.
        packageVersion:
          type: string
          description: The version of the custom app package.
        deploymentStatus:
          type: string
          description: The deployment status of the custom app.
          enum:
            - pending
            - deployed
            - failed
        createdBy:
          type: string
          description: The unique identifier of the user who created the custom app.
        createdOn:
          type: string
          format: date-time
          description: The date and time the custom app was created (ISO-8601 format).
        updatedBy:
          type: string
          description: The unique identifier of the user who last updated the custom app.
        updatedOn:
          type: string
          format: date-time
          description: The date and time the custom app was last updated (ISO-8601 format).
        status:
          type: string
          description: The status of the custom app.
          enum:
            - active
            - deleted
      example:
        appId: d88d505d-5199-11ee-a644-522476618ae8
        appType: hypersync
        isCustom: true
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        packageName: Name of the package
        packageVersion: '1.0'
        deploymentStatus: deployed
        createdBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        createdOn: 2025-01-12T18:26:10.00.5365Z
        updatedBy: 82d7c228-8bcd-11e9-a94b-ab3de8494987
        updatedOn: 2025-01-12T18:26:10.00.5365Z
        status: active
    CustomAppCollection:
      type: array
      description: Collection of custom apps.
      items:
        $ref: '#/components/schemas/CustomApp'
    LogEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the log event.
        timestamp:
          type: string
          format: date-time
          description: The timestamp of when the log event occurred (ISO-8601 format).
        level:
          type: string
          description: The severity of the log event.
          enum:
            - debug
            - info
            - warning
            - error
        message:
          type: string
          description: The log event message.
        detail:
          type: string
          description: Detailed description of the log event.
        orgId:
          type: string
          format: uuid
          description: The unique identifier for the organization.
        userId:
          type: string
          format: uuid
          description: The unique identifier for the user who uploaded the custom app
      example:
        id: d88d505d-5199-11ee-a644-522476618ae8
        timestamp: 2025-01-12T18:26:10.00.5365Z
        level: debug
        message: Log event message
        detail: Log event detail
        orgId: ce83e3cd-5199-11ee-a644-522476618ae8
        userId: d2363cab-5199-11ee-a644-522476618ae8
    LogEventCollection:
      type: array
      description: Collection of log events
      items:
        $ref: '#/components/schemas/LogEvent'
    CustomAppStats:
      type: object
      properties:
        appId:
          type: string
          format: uuid
          description: The unique identifier for the custom app.
        orgId:
          type: string
          format: uuid
          description: The unique identifier for the organization.
        hypersyncCount:
          type: number
          description: The number of active hypersyncs in for this app and orgId.
      example:
        appId: d88d505d-5199-11ee-a644-522476618ae8
        orgId: d7cf0a26-5199-11ee-a644-522476618ae8
        hypersyncCount: 2
